HANDLE

Section: Memory Management Utilities ()
Updated: June 12 1992
Index Return to Main Contents

NAME

Handle - Handle works with Shared mixin to provide reference count of shared pointers.

SYNOPSIS

DESCRIPTION

Handle<Type> works with Shared mixin on the object to provide a very simple scheme of memory management with reference count. Handles to objects are stored in containers or other data structures, instead of pointers to objects, if these objects are shared. If your design of the object hierarchy has layers, from the root O1 to the leaves On, parent node Oi should store Oj, or a handle to Oj, for automatic deletion of all the nodes in the tree when the root O1 is deleted. In essence, you design an acyclic graph for your hierarchy. Nodes can be shared with reference count. Backward pointers that create cycles in your network should be broken up by storing pointers instead of handles. Note that pointers stored in COOL containers are not deleted, while objects are. The overhead of a handle comes from checking for null pointer, and updating the reference count.

BASE CLASSES

None.

FRIEND CLASSES

None.

CONSTRUCTORS

inline Handle<Type> ();: Creates an empty Handle, with pointer initialized to NULL.
inline Handle<Type> (Type* ptr);: Creates a handle from a pointer. If pointer ptr is non null, increments reference count on object pointed to.
inline Handle<Type> (Type& obj);: Creates a handle from a reference to object obj, and increments its reference count.
inline Handle<Type> (const Handle<Type>& rhs);: Copies a handle rhs. Increments reference count on object pointed to.
inline ~Handle<Type>();: Decrement reference count on object pointed to. Deletes object if there is no more reference to it.

MEMBER FUNCTIONS

inline Handle<Type>& operator= (Type* ptr);
inline Handle<Type>& operator= (Type& obj);: Overloads assignment operator to bind handle lhs to pointer ptr, or object obj. Increments reference count on object as needed.
inline Handle<Type>& operator= (const Handle<Type>& rhs);: Overloads assignment operator to copy handle rhs over to handle lhs. lhs object is unreferenced, and rhs object is referenced.
inline Type* operator-> ();: Overloads indirection operator to access object. Null handle creates segmentation fault just as null pointer.
inline operator Type* ();
inline operator Type& ();: Allows automatic conversion from a Handle<Type> to a pointer or to a reference. Conversion to reference requires a non null handle.
typedef Type* Type##P;
typedef Type& Type##R;
typedef Handle<Type> Type##H;: Defines short type names respectively for pointer, reference, and handle.

FRIEND FUNCTIONS

inline friend Type* ptr (Handle<Type>& h);
inline friend Type& ref (Handle<Type>& h);
inline friend Handle<Type> hdl (Type* ptr=NULL);: Manual conversion among handle, pointer, and reference. Conversion to a reference requires a non null handle.
inline friend Boolean operator== (const Handle<Type>& h1, const Handle<Type>& h2);
inline friend Boolean operator!= (const Handle<Type>& h1, const Handle<Type>& h2);
inline friend Boolean operator<= (const Handle<Type>& h1, const Handle<Type>& h2);: Overloads comparison operators to compare pointer values stored in handles.
inline friend ostream& operator<< (ostream& os, const Handle<Type>& h);
inline friend ostream& operator<< (ostream& os, const Handle<Type>* h);: Overloads output operator for both reference and pointer to a handle h.

EXAMPLE

  Assuming class Vector<int> : public Shared { ... };
  Vector<Handle<Vector<int>>> c(3, hdl(NULL));

  Vector<int>P p0 = new Vector<int>(1, 1, 1);

  c[0] = p0;
  c[1] = *p0;
  c[2] = hdl(p0);

  Vector<int>P p = c[1];
  Vector<int>R r = c[2];
  Vector<int>H h = c[0];

  p->reference_count();
  r.reference_count();
  h->reference_count();

COPYRIGHT

Permission is granted to any individual or institution to use, copy, modify, and distribute this software, provided that this complete copyright and permission notice is maintained, intact, in all copies and supporting documentation.

General Electric Company provides this software "as is" without express or implied warranty.

This document was created by man2html, using the manual pages.
Time: 00:40:36 GMT, March 30, 2022